Skip to content

docs: add AGENTS.md and reorganize project documentation#6871

Open
Sunny6889 wants to merge 12 commits into
tronprotocol:developfrom
Little-Peony:fix_readme
Open

docs: add AGENTS.md and reorganize project documentation#6871
Sunny6889 wants to merge 12 commits into
tronprotocol:developfrom
Little-Peony:fix_readme

Conversation

@Sunny6889

@Sunny6889 Sunny6889 commented Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What does this PR do?

  • Adds AGENTS.md — a concise build/test/architecture guide for AI coding assistants and new contributors, with the high-frequency constraints to respect.
  • Adds a Documentation index to the README linking every guide.
  • Moves the protobuf protocol doc and METRICS_CHANGELOG.md into docs/ with consistent lower-case names; marks two outdated protocol copies as superseded.
  • Adds Super-Representative private-key security notes to the config guide.
  • Removes unused CI configs (.codeclimate.yml, sonar-project.properties, stale Sonar entries in verification metadata) and the .dockerignore file.

Why are these changes required?

  • No single entry point told contributors (or AI assistants) how to build, test, and navigate the codebase, or which invariants must not be broken.
  • Several guides existed but were unlinked from the README; the protocol doc and metrics changelog cluttered the repo root and the proto tree.
  • Two 2022-era protocol copies gave no hint they were stale.
  • The config guide never warned that a plaintext block-producing key can leak via file permissions or be committed to Git.
  • .codeclimate.yml / sonar-project.properties are no longer used by CI.

This PR has been tested by:

  • Unit Tests — N/A (docs + config-file removal only; no code paths touched)
  • Manual Testing — verified every claim in AGENTS.md against the build config and sources, and that all moved paths and cross-doc links resolve

Follow up

None.

Extra details

@abn2357

abn2357 commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Two issues and one optional naming nit as below, please consider whether modifications are required.:

  • Reconcile the remaining Sonar references

    This PR removes .codeclimate.yml and sonar-project.properties because they are no longer used by CI, but Sonar-related references remain:

    • framework/build.gradle:3 still applies org.sonarqube.
    • CONTRIBUTING.md:150 says that the Sonar scanner is automatically triggered for pull requests.
    • CONTRIBUTING.md:161 requires contributions to pass the Sonar scanner test.

    Please update CONTRIBUTING.md to reflect the current CI process.

  • Fix the relative source link after moving the metrics changelog

    After moving METRICS_CHANGELOG.md into docs/, the link to common/src/main/java/org/tron/common/prometheus/ on line 22 now resolves to the non-existent path:

    docs/common/src/main/java/org/tron/common/prometheus/

    Please change the link target from:

    common/src/main/java/org/tron/common/prometheus/

    to:

    ../common/src/main/java/org/tron/common/prometheus/

  • [Nit] Consider using kebab-case consistently

    Most files under docs/ use kebab-case, while metrics_changelog.md uses snake_case. Consider renaming it to metrics-changelog.md for consistency with names such as protobuf-protocol-document.md.

@Sunny6889

Sunny6889 commented Jul 14, 2026

Copy link
Copy Markdown
Contributor Author

Two issues and one optional naming nit as below, please consider whether modifications are required.:

  • Reconcile the remaining Sonar references
    This PR removes .codeclimate.yml and sonar-project.properties because they are no longer used by CI, but Sonar-related references remain:

    • framework/build.gradle:3 still applies org.sonarqube.
    • CONTRIBUTING.md:150 says that the Sonar scanner is automatically triggered for pull requests.
    • CONTRIBUTING.md:161 requires contributions to pass the Sonar scanner test.

    Please update CONTRIBUTING.md to reflect the current CI process.

  • Fix the relative source link after moving the metrics changelog
    After moving METRICS_CHANGELOG.md into docs/, the link to common/src/main/java/org/tron/common/prometheus/ on line 22 now resolves to the non-existent path:
    docs/common/src/main/java/org/tron/common/prometheus/
    Please change the link target from:
    common/src/main/java/org/tron/common/prometheus/
    to:
    ../common/src/main/java/org/tron/common/prometheus/

  • [Nit] Consider using kebab-case consistently
    Most files under docs/ use kebab-case, while metrics_changelog.md uses snake_case. Consider renaming it to metrics-changelog.md for consistency with names such as protobuf-protocol-document.md.

very good suggestion, will fix all.

@lvs0075 lvs0075 added this to the GreatVoyage-v4.8.2 milestone Jul 14, 2026
halibobo1205
halibobo1205 reviewed Jul 14, 2026
View reviewed changes
Comment thread framework/build.gradle
@halibobo1205
halibobo1205 self-requested a review July 14, 2026 10:24
@Sunny6889
Sunny6889 changed the base branch from release_v4.8.2 to develop July 16, 2026 05:56
@halibobo1205 halibobo1205 removed this from the GreatVoyage-v4.8.2 milestone Jul 17, 2026
@Sunny6889 Sunny6889 changed the title docs: reorganize documentation and remove stale CI configs docs: add AGENTS.md and reorganize project documentation Jul 20, 2026
Little-Peony and others added 12 commits July 20, 2026 11:14
@Little-Peony
docs(readme): add Documentation section linking guides and protocol doc
773ab21
@Little-Peony
docs(config): add super-representative private-key security notes
1a3bafc
@Little-Peony
docs: move protocol document into docs/ with a shorter name
cbf9eae
@Little-Peony @claude
docs: move metrics changelog into docs/ and link from README
0ca2740 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Little-Peony
docs: mark outdated protobuf protocol copies as superseded
c020830
@Little-Peony @claude
chore(ci): remove unused CodeClimate and Sonar configs
f2fb426 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Little-Peony
delete .dockerignore
acac4d5
@Little-Peony
modify chinese
f966422
@Little-Peony
docs: drop stale Sonar references and fix metrics changelog link
8ead205
@Little-Peony
chore: remove unused Sonar entries from verification-metadata
565ae0f
@Little-Peony
docs: add AGENTS.md for AI assistants and contributors
84c44b6
@Little-Peony
docs: correct AGENTS.md platform and build details
0ca52e5 
- Note the build fails fast on a JDK/arch mismatch
- Scope the lint helper comment to framework main
- Fix the generated-protobuf source path (core/, api/ subdirs)
- Add the platform module (arch-specific source sets) to the layout
- List both plugins jars (Toolkit, ArchiveManifest)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@317787106 317787106 317787106 approved these changes
@halibobo1205 halibobo1205 Awaiting requested review from halibobo1205
+1 more reviewer
@bombaycubza-svg bombaycubza-svg bombaycubza-svg approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

topic:documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

7 participants

@Sunny6889 @abn2357 @317787106 @halibobo1205 @bombaycubza-svg @lvs0075 @Little-Peony